home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 17 / CU Amiga Magazine's Super CD-ROM 17 (1997)(EMAP Images)(GB)[!][issue 1997-12].iso / CUCD / Programming / DiceSource / src / alib / csup / commodities_support / autodocs.asm < prev    next >
Encoding:
Assembly Source File  |  1994-02-14  |  16.7 KB  |  543 lines
  1.  
  2. ******* amiga.lib/ArgArrayDone ***********************************************
  3. *
  4. *   NAME
  5. *    ArgArrayDone -- release the memory allocated by a previous call
  6. *            to ArgArrayInit(). (V36)
  7. *
  8. *   SYNOPSIS
  9. *    ArgArrayDone();
  10. *
  11. *    VOID ArgArrayDone(VOID);
  12. *
  13. *   FUNCTION
  14. *    This function frees memory and does cleanup required after a
  15. *    call to ArgArrayInit(). Don't call this until you are done using
  16. *    the ToolTypes argument strings.
  17. *
  18. *   SEE ALSO
  19. *    ArgArrayInit()
  20. *
  21. ******************************************************************************
  22.  
  23.  
  24. ******* amiga.lib/ArgArrayInit ***********************************************
  25. *
  26. *   NAME
  27. *    ArgArrayInit -- allocate and initialize a tooltype array. (V36)
  28. *
  29. *   SYNOPSIS
  30. *    ttypes = ArgArrayInit(argc,argv);
  31. *
  32. *    UBYTE **ArgArrayInit(LONG,UBYTE **);
  33. *
  34. *   FUNCTION
  35. *    This function returns a null-terminated array of strings
  36. *    suitable for sending to icon.library/FindToolType(). This array will
  37. *    be the ToolTypes array of the program's icon, if it was started from
  38. *    Workbench. It will just be 'argv' if the program was started from
  39. *    a shell.
  40. *
  41. *    Pass ArgArrayInit() your startup arguments received by main().
  42. *
  43. *    ArgArrayInit() requires that icon.library be open (even if the caller
  44. *    was started from a shell, so that the function FindToolType() can be
  45. *    used) and may call GetDiskObject(), so clean up is necessary when
  46. *    the strings are no longer needed. The function ArgArrayDone() does
  47. *    just that.
  48. *
  49. *   INPUTS
  50. *    argc - the number of arguments in argv, 0 when started from Workbench
  51. *    argv - an array of pointers to the program's arguments, or the
  52. *           Workbench startup message when started from WB.
  53. *
  54. *   RESULTS
  55. *    ttypes - the initialized argument array or NULL if it could not be
  56. *             allocated
  57. *
  58. *   EXAMPLE
  59. *    Use of these routines facilitates the use of ToolTypes or command-
  60. *    line arguments to control end-user parameters in Commodities
  61. *    applications. For example, a filter used to trap a keystroke for
  62. *    popping up a window might be created by something like this:
  63. *
  64. *            char   *ttypes  = ArgArrayInit(argc, argv);
  65. *            CxObj   *filter = UserFilter(ttypes, "POPWINDOW", "alt f1");
  66. *
  67. *               ... with ...
  68. *
  69. *               CxObj *UserFilter(char **tt, char *action_name,
  70. *                  char *default_descr)
  71. *        {
  72. *        char *desc;
  73. *
  74. *            desc = FindToolType(tt,action_name);
  75. *
  76. *            return(CxFilter((ULONG)(desc? desc: default_descr)));
  77. *        }
  78. *
  79. *    In this way the user can assign "alt f2" to the action by
  80. *    entering a tooltype in the program's icon of the form:
  81. *
  82. *        POPWINDOW=alt f2
  83. *
  84. *    or by starting the program from the CLI like so:
  85. *
  86. *        myprogram "POPWINDOW=alt f2"
  87. *
  88. *   NOTE
  89. *    Your program must open icon.library and set up IconBase before calling
  90. *    this routine. In addition IconBase must remain valid until after
  91. *    ArgArrayDone() has been called!
  92. *
  93. *   SEE ALSO
  94. *    ArgArrayDone(), ArgString(), ArgInt(), icon.library/FindToolType()
  95. *
  96. ******************************************************************************
  97.  
  98.  
  99. ******* amiga.lib/ArgInt *****************************************************
  100. *
  101. *   NAME
  102. *    ArgInt -- return an integer value from a ToolTypes array. (V36)
  103. *
  104. *   SYNOPSIS
  105. *    value = ArgInt(tt,entry,defaultval)
  106. *
  107. *    LONG ArgInt(UBYTE **,STRPTR,LONG);
  108. *
  109. *   FUNCTION
  110. *    This function looks in the ToolTypes array 'tt' returned
  111. *    by ArgArrayInit() for 'entry' and returns the value associated
  112. *    with it. 'tt' is in standard ToolTypes format such as:
  113. *
  114. *        ENTRY=Value
  115. *
  116. *    The Value string is passed to atoi() and the result is returned by
  117. *    this function.
  118. *
  119. *    If 'entry' is not found, the integer 'defaultval' is returned.
  120. *
  121. *   INPUTS
  122. *    tt - a ToolTypes array as returned by ArgArrayInit()
  123. *    entry - the entry in the ToolTypes array to search for
  124. *    defaultval - the value to return in case 'entry' is not found within
  125. *             the ToolTypes array
  126. *
  127. *   RESULTS
  128. *    value - the value associated with 'entry', or defaultval if 'entry'
  129. *        is not in the ToolTypes array
  130. *
  131. *   NOTES
  132. *    This function requires that dos.library V36 or higher be opened.
  133. *
  134. *   SEE ALSO
  135. *    ArgArrayInit()
  136. *
  137. ******************************************************************************
  138.  
  139.  
  140. ******* amiga.lib/ArgString **************************************************
  141. *
  142. *   NAME
  143. *    ArgString -- return a string pointer from a ToolTypes array. (V36)
  144. *
  145. *   SYNOPSIS
  146. *    string = ArgString(tt,entry,defaultstring)
  147. *
  148. *    STRPTR ArgString(UBYTE **,STRPTR,STRPTR);
  149. *
  150. *   FUNCTION
  151. *    This function looks in the ToolTypes array 'tt' returned
  152. *    by ArgArrayInit() for 'entry' and returns the value associated
  153. *    with it. 'tt' is in standard ToolTypes format such as:
  154. *
  155. *        ENTRY=Value
  156. *
  157. *    This function returns a pointer to the Value string.
  158. *
  159. *    If 'entry' is not found, 'defaultstring' is returned.
  160. *
  161. *   INPUTS
  162. *    tt - a ToolTypes array as returned by ArgArrayInit()
  163. *    entry - the entry in the ToolTypes array to search for
  164. *    defaultstring - the value to return in case 'entry' is not found within
  165. *                the ToolTypes array
  166. *
  167. *   RESULTS
  168. *    value - the value associated with 'entry', or defaultstring if 'entry'
  169. *        is not in the ToolTypes array
  170. *
  171. *   SEE ALSO
  172. *    ArgArrayInit()
  173. *
  174. ******************************************************************************
  175.  
  176.  
  177. ******* amiga.lib/CxCustom ***************************************************
  178. *
  179. *   NAME
  180. *    CxCustom -- create a custom commodity object. (V36)
  181. *
  182. *   SYNOPSIS
  183. *    customObj = CxCustom(action,id);
  184. *
  185. *    CxObj *CxCustom(LONG(*)(),LONG);
  186. *
  187. *   FUNCTION
  188. *    This function creates a custom commodity object. The action
  189. *    of this object on receiving a commodity message is to call a
  190. *    function of the application programmer's choice.
  191. *
  192. *    The function provided ('action') will be passed a pointer to
  193. *    the actual commodities message (in commodities private data
  194. *    space), and will actually execute as part of the input handler
  195. *    system task. Among other things, the value of 'id' can be
  196. *    recovered from the message by using the function CxMsgID().
  197. *
  198. *    The purpose of this function is two-fold. First, it allows
  199. *    programmers to create Commodities Exchange objects with
  200. *    functionality that was not imagined or chosen for inclusion
  201. *    by the designers. Secondly, this is the only way to act
  202. *    synchronously with Commodities.
  203. *
  204. *    This function is a C-language macro for CreateCxObj(), defined
  205. *    in <libraries/commodities.h>.
  206. *
  207. *   INPUTS
  208. *    action - a function to call whenever a message reaches the object
  209. *    id - a message id to assign to the object
  210. *
  211. *   RESULTS
  212. *    customObj - a pointer to the new custom object, or NULL if it could
  213. *            not be created.
  214. *
  215. *  SEE ALSO
  216. *    commodities.library/CreateCxObj(), commodities.library/CxMsgID()
  217. *
  218. ******************************************************************************
  219.  
  220.  
  221. ******* amiga.lib/CxDebug ****************************************************
  222. *
  223. *   NAME
  224. *    CxDebug -- create a commodity debug object. (V36)
  225. *
  226. *   SYNOPSIS
  227. *    debugObj = CxDebug(id);
  228. *
  229. *    CxObj *CxDebug(LONG);
  230. *
  231. *   FUNCTION
  232. *    This function creates a Commodities debug object. The action of this
  233. *    object on receiving a Commodities message is to print out information
  234. *    about the Commodities message through the serial port (using the
  235. *    kprintf() routine). The value of 'id' will also be displayed.
  236. *
  237. *    Note that this is a synchronous occurrence (the printing is done by
  238. *    the input device task). If screen or file output is desired, using a
  239. *    sender object instead of a debug object is necessary, since such
  240. *    output is best done by your application process.
  241. *
  242. *    This function is a C-language macro for CreateCxObj(), defined
  243. *    in <libraries/commodities.h>.
  244. *
  245. *   INPUTS
  246. *    id - the id to assign to the debug object, this value is output
  247. *         whenever the debug object sends data to the serial port.
  248. *
  249. *   RESULTS
  250. *    debugObj - a pointer to the debug object, or NULL if it could
  251. *           not be created.
  252. *
  253. *   SEE ALSO
  254. *    commodities.library/CreateCxObj(), CxSender(), debug.lib/kprintf()
  255. *
  256. ******************************************************************************
  257.  
  258.  
  259. ******* amiga.lib/CxFilter ***************************************************
  260. *
  261. *   NAME
  262. *    CxFilter -- create a commodity filter object. (V36)
  263. *
  264. *   SYNOPSIS
  265. *    filterObj = CxFilter(description);
  266. *
  267. *    CxObj *CxFilter(STRPTR)
  268. *
  269. *   FUNCTION
  270. *    Creates an input event filter object that matches the
  271. *    'description' string. If 'description' is NULL, the filter will not
  272. *    match any messages.
  273. *
  274. *    A filter may be modified by the functions SetFilter(), using
  275. *    a description string, and SetFilterIX(), which takes a
  276. *    binary Input Expression as a parameter.
  277. *
  278. *    This function is a C-language macro for CreateCxObj(), defined
  279. *    in <libraries/commodities.h>.
  280. *
  281. *   INPUTS
  282. *    description - the description string in the same format as strings
  283. *              expected by commodities.library/SetFilter()
  284. *
  285. *   RESULTS
  286. *    filterObj - a pointer to the filter object, or NULL if there
  287. *            was not enough memory. If there is a problem in the
  288. *            description string, the internal error code of the filter
  289. *            object will be set to so indicate. This error code may be
  290. *            interrogated using the function CxObjError().
  291. *
  292. *   SEE ALSO
  293. *    commodities.library/CreateCxObj(), commodities.library/SetFilter(),
  294. *    commodities.library/SetFilterIX(), commodities.library/CxObjError()
  295. *
  296. ******************************************************************************
  297.  
  298.  
  299. ******* amiga.lib/CxSender ***************************************************
  300. *
  301. *   NAME
  302. *    CxSender -- create a commodity sender object. (V36)
  303. *
  304. *   SYNOPSIS
  305. *    senderObj = CxSender(port,id)
  306. *
  307. *    CxObj *CxSender(struct MsgPort *,LONG);
  308. *
  309. *   FUNCTION
  310. *    This function creates a Commodities sender object. The action
  311. *    of this object on receiving a Commodities message is to copy the
  312. *    Commodities message into a standard Exec Message, to put the value
  313. *    'id' in the message as well, and to send the message off to the
  314. *    message port 'port'.
  315. *
  316. *    The value 'id' is used so that an application can monitor
  317. *    messages from several senders at a single port. It can be retrieved
  318. *    from the Exec message by using the function CxMsgID(). The value can
  319. *    be a simple integer ID, or a pointer to some application data
  320. *    structure.
  321. *
  322. *    Note that Exec messages sent by sender objects arrive
  323. *    asynchronously at the destination port. Do not assume anything about
  324. *    the status of the Commodities message which was copied into the Exec
  325. *    message you received.
  326. *
  327. *    All Exec messages sent to your ports must be replied. Messages may be
  328. *    replied after the sender object has been deleted.
  329. *
  330. *    This function is a C-language macro for CreateCxObj(), defined
  331. *    in <libraries/commodities.h>.
  332. *
  333. *   INPUTS
  334. *    port - the port for the sender to send messages to
  335. *    id - the id of the messages sent by the sender
  336. *
  337. *   RESULTS
  338. *    senderObj - a pointer to the sender object, or NULL if it could
  339. *            not be created.
  340. *
  341. *   SEE ALSO
  342. *    commodities.library/CreateCxObj(), commodities.library/CxMsgID(),
  343. *    exec.library/PutMsg(), exec.library/ReplyMsg()
  344. *
  345. ******************************************************************************
  346.  
  347.  
  348. ******* amiga.lib/CxSignal ***************************************************
  349. *
  350. *   NAME
  351. *    CxSignal -- create a commodity signaller object. (V36)
  352. *
  353. *   SYNOPSIS
  354. *    signalerObj = CxSignal(task,signal);
  355. *
  356. *    CxObj *CxSignal(struct Task *,LONG);
  357. *
  358. *   FUNCTION
  359. *    This function creates a Commodities signal object. The action
  360. *    of this object on receiving a Commodities message is to
  361. *    send the 'signal' to the 'task'. The caller is responsible
  362. *    for allocating the signal and determining the proper task ID.
  363. *
  364. *    Note that 'signal' is the signal value as returned by AllocSignal(),
  365. *    not the mask made from that value.
  366. *
  367. *    This function is a C-language macro for CreateCxObj(), defined
  368. *    in <libraries/commodities.h>.
  369. *
  370. *   INPUTS
  371. *    task - the task for the signaller to signal
  372. *    signal - the signal bit number for the signaller to send
  373. *
  374. *   RESULTS
  375. *    signallerObj - a pointer to the signaller object, or NULL if it could
  376. *               not be created.
  377. *
  378. *   SEE ALSO
  379. *    commodities.library/CreateCxObj(), exec.library/FindTask()
  380. *    exec.library/Signal(), exec.library/AllocSignal(),
  381. *
  382. ******************************************************************************
  383.  
  384.  
  385. ******* amiga.lib/CxTranslate ************************************************
  386. *
  387. *   NAME
  388. *    CxTranslate -- create a commodity translator object. (V36)
  389. *
  390. *   SYNOPSIS
  391. *    translatorObj = CxTranslate(ie);
  392. *
  393. *    CxObj *CxTranslate(struct InputEvent *);
  394. *
  395. *   FUNCTION
  396. *    This function creates a Commodities 'translator' object.
  397. *    The action of this object on receiving a Commodities message is to
  398. *    replace that message in the commodities network with a chain of
  399. *    Commodities input messages.
  400. *
  401. *    There is one new Commodities input message generated for each input
  402. *    event in the linked list starting at 'ie' (and NULL terminated). The
  403. *    routing information of the new input messages is copied from the input
  404. *    message they replace.
  405. *
  406. *    The linked list of input events associated with a translator object
  407. *    can be changed using the SetTranslate() function.
  408. *
  409. *    If 'ie' is NULL, the null translation occurs: that is, the original
  410. *    commodities input message is disposed, and no others are created to
  411. *    take its place.
  412. *
  413. *    This function is a C-language macro for CreateCxObj(), defined
  414. *    in <libraries/commodities.h>.
  415. *
  416. *   INPUTS
  417. *    ie - the input event list used as replacement by the translator
  418. *
  419. *   RESULTS
  420. *    translatorObj - a pointer to the translator object, or NULL if it could
  421. *                not be created.
  422. *
  423. *   SEE ALSO
  424. *    commodities.library/CreateCxObj(), commodities.library/SetTranslate()
  425. *
  426. ******************************************************************************
  427.  
  428.  
  429. ******* amiga.lib/FreeIEvents ************************************************
  430. *
  431. *   NAME
  432. *    FreeIEvents -- free a chain of input events allocated by
  433. *               InvertString(). (V36)
  434. *
  435. *   SYNOPSIS
  436. *    FreeIEvents(events)
  437. *
  438. *    VOID FreeIEvents(struct InputEvent *);
  439. *
  440. *   FUNCTION
  441. *    This function frees a linked list of input events as obtained from
  442. *    InvertString().
  443. *
  444. *   INPUTS
  445. *       events - the list of input events to free, may be NULL.
  446. *
  447. *   SEE ALSO
  448. *    InvertString()
  449. *
  450. ******************************************************************************
  451.  
  452.  
  453. ******* amiga.lib/HotKey *****************************************************
  454. *
  455. *   NAME
  456. *    HotKey -- create a commodity triad. (V36)
  457. *
  458. *   SYNOPSIS
  459. *    filterObj = Hotkey(description,port,id);
  460. *
  461. *    CxObj *HotKey(STRPTR,struct MsgPort *,LONG);
  462. *
  463. *   FUNCTION
  464. *    This function creates a triad of commodity objects to accomplish a
  465. *    high-level function.
  466. *
  467. *    The three objects are a filter, which is created to match by the call
  468. *    CxFilter(description), a sender created by the call CxSender(port,id),
  469. *    and a translator which is created by CxTranslate(NULL), so that it
  470. *    swallows any commodity input event messages that are passed down by
  471. *    the filter.
  472. *
  473. *    This is the simple way to get a message sent to your program when the
  474. *    user performs a particular input action.
  475. *
  476. *    It is strongly recommended that the ToolTypes environment be used to
  477. *    allow the user to specify the input descriptions for your application's
  478. *    hotkeys.
  479. *
  480. *   INPUTS
  481. *    description - the description string to use for the filter in the same
  482. *              format as accepted by commodities.library/SetFilter()
  483. *    port - port for the sender to send messages to.
  484. *    id - id of the messages sent by the sender
  485. *
  486. *   RESULTS
  487. *    filterObj - a pointer to a filter object, or NULL if it could
  488. *            not be created.
  489. *
  490. *   SEE ALSO
  491. *    CxFilter(), CxSender(), CxTranslate(),
  492. *    commodities.library/CxObjError(), commodities.library/SetFilter()
  493. *
  494. ******************************************************************************
  495.  
  496.  
  497. ******* amiga.lib/InvertString ***********************************************
  498. *
  499. *   NAME
  500. *    InvertString -- produce input events that would generate the
  501. *            given string. (V36)
  502. *
  503. *   SYNOPSIS
  504. *    events = InvertString(str,km)
  505. *
  506. *    struct InputEvent *InvertString(STRPTR,struct KeyMap *);
  507. *
  508. *   FUNCTION
  509. *    This function returns a linked list of input events which would
  510. *    translate into the string using the supplied keymap (or the system
  511. *    default keymap if 'km' is NULL).
  512. *
  513. *    'str' is null-terminated and may contain:
  514. *       - ANSI character codes
  515. *       - backslash escaped characters:
  516. *        \n   -   CR
  517. *        \r   -   CR
  518. *        \t   -   TAB
  519. *        \0   -   illegal, do not use!
  520. *        \\   -   backslash
  521. *       - a text description of an input event as used by ParseIX(),
  522. *         enclosed in angle brackets.
  523. *
  524. *    An example is:
  525. *          abc<alt f1>\nhi there.
  526. *
  527. *   INPUTS
  528. *    str - null-terminated string to convert to input events
  529. *    km - keymap to use for the conversion, or NULL to use the default
  530. *         keymap.
  531. *
  532. *   RESULTS
  533. *    events - a chain of input events, or NULL if there was a problem. The
  534. *         most likely cause of failure is an illegal description
  535. *         enclosed in angled brackets.
  536. *
  537. *         This chain should eventually be freed using FreeIEvents().
  538. *
  539. *   SEE ALSO
  540. *    commodities.library/ParseIX(), FreeIEvents()
  541. *
  542. ******************************************************************************
  543.